Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags.

Customizing a Joystick Configuration

A configuration file must be defined that gives the available buttons and axes on a joystick, and maps these inputs to functionality on the robot.

The easiest thing for a user to modify is the "scale" attribute of the joystick mappings. For example, changing the speed of arm motion on any or all axes can be accomplished by editing the scale under {arm: x, y, z, wx, wy, wz}.

To move functionality to a different part of the controller, the "name" attributes can be edited for each mapping. The name refers to the joystick input, for example, 'r_joy_x' for the horizontal movement of the right joystick on the controller, or 'triangle' for the triangle button.

After changing the name, care should be taken to select the correct function for that input. For example, a virtual axis can be constructed from two buttons by selecting 'difference' and setting name1 = <first button> and name2 = second_button.

The available input types are given in the table below.

The config file for the ps3 controller is shown below, with comments inline.

# Everything is a element of the joy_config dictionary
joy_config:
  my_joystick: 'sixaxis' # The joystick name (not currently used...)


# Sony PS3 Sixaxis Controller
# The joystick buttons/axes are defined under the "controller" key.
# Buttons are digital [0,1] while axes are analog [0,-1]
  controller:
    l_joy_x:      { type: 'axis',   id: 0 }
    l_joy_y:      { type: 'axis',   id: 1 }
    r_joy_x:      { type: 'axis',   id: 2 }
    r_joy_y:      { type: 'axis',   id: 3 }
    select:       { type: 'button', id: 0 }
    l_joy_click:  { type: 'button', id: 1 }
    r_joy_click:  { type: 'button', id: 2 }
    start:        { type: 'button', id: 3 }
    pad_up:       { type: 'button', id: 4 }
    pad_right:    { type: 'button', id: 5 }
    pad_down:     { type: 'button', id: 6 }
    pad_left:     { type: 'button', id: 7 }
    l2:           { type: 'button', id: 8 }
    r2:           { type: 'button', id: 9 }
    l1:           { type: 'button', id: 10 }
    r1:           { type: 'button', id: 11 }
    triangle:     { type: 'button', id: 12 }
    circle:       { type: 'button', id: 13 }
    x:            { type: 'button', id: 14 }
    square:       { type: 'button', id: 15 }
    home:         { type: 'button', id: 16 }

# Command mappings; this is what gets used in the program.
  mapping:

    #The gui tag 
    gui:
      #run_stop: { type: 'and', params: { name1: 'select', name2: 'start' } }
      
      # if mode_select is defined, the next 6 must be defined too
      mode_select:  { type: 'button', params: { name1: 'start' }
      use_camera_frame:  { type: 'button', params: { name1: 'r2' } }
      select_view:  { type: 'button', params: { name1: 'l1' } }
      select_head:  { type: 'button', params: { name1: 'pad_up' } }
      select_l_arm:  { type: 'button', params: { name1: 'pad_left' } }
      select_r_arm:  { type: 'button', params: { name1: 'pad_right' } }
      select_base:  { type: 'button', params: { name1: 'pad_down' } }
      
      # if camera_select is defined, the next 5 must be defined too
      camera_select:  { type: 'button', params: { name1: 'select' } }
      select_narrow:  { type: 'button', params: { name1: 'x' } }
      select_wide:  { type: 'button', params: { name1: 'triangle' } }
      select_r_forearm:  { type: 'button', params: { name1: 'circle' } }
      select_l_forearm:  { type: 'button', params: { name1: 'square' } }
      select_r_gripper:  { type: 'button', params: { name1: 'r1' } }

    #controls for moving the camera in rviz
    view:
      radius:    { type: 'difference', params: { name1: 'l2', name2: 'l1', scale: 2} }
      azimuth:    { type: 'axis',       params: { name1: 'l_joy_x', scale: -1} }
      elevation:    { type: 'axis',       params: { name1: 'l_joy_y', scale: 1} }
      suppress: { type: 'or',       params: { name1: 'select', name2: 'start' } }

    # pr2 base and spine control
    base: 
      suppress: { type: 'or',       params: { name1: 'select', name2: 'start' } }
      deadman:  { type: 'button',   params: { name1: 'l1' } }
      turbo:    { type: 'button',   params: { name1: 'r1', scale: 1.5 } }
      x:        { type: 'axis',     params: { name1: 'r_joy_y', scale: 0.3} }
      y:        { type: 'axis',     params: { name1: 'r_joy_x', scale: 0.3} }
      wz:       { type: 'axis',     params: { name1: 'l_joy_x', scale: 0.3} }
      torso:    { type: 'difference', params: { name1: 'triangle', name2: 'x'} }

      
    # left and right arm control
    arm:
      suppress:  { type: 'or', params: { name1: 'select', name2: 'start' } }
      x:    { type: 'axis',       params: { name1: 'l_joy_y', scale: 0.1} }
      y:    { type: 'axis',       params: { name1: 'l_joy_x', scale: 0.1} }
      z:    { type: 'difference', params: { name1: 'l2', name2: 'l1', scale: -0.1} }
      wx:   { type: 'difference', params: { name1: 'r2', name2: 'r1', scale: 0.5} }
      wy:   { type: 'axis',       params: { name1: 'r_joy_y', scale: -0.4} }
      wz:   { type: 'axis',       params: { name1: 'r_joy_x', scale: 0.4} }
      gripper:  { type: 'difference', params: { name1: 'square',   name2: 'circle'} }
      #pre-defined gripper orientations
      above:    { type: 'button', params: { name1: 'pad_up' } }
      right:    { type: 'button', params: { name1: 'pad_right' } }
      left:    { type: 'button', params: { name1: 'pad_left' } }
      front:    { type: 'button', params: { name1: 'pad_down' } }
      tuck:    { type: 'and', params: { name1: 'square', name2: 'circle' } }
      
      #stuff for pr2_gripper_grasp_adjust (optional)
      adjust_find:  { type: 'and', params: { name1: 'circle', name2: 'triangle' } }
      adjust_clear:  { type: 'and', params: { name1: 'square', name2: 'triangle' } }
      adjust_select:  { type: 'toggle', params: { name1: 'triangle' } }
      adjust_go:    { type: 'toggle', params: { name1: 'x' } }

    # head control
    head:
      suppress: { type: 'or', params: { name1: 'select', name2: 'start' } }
      pan:  { type: 'axis',       params: { name1: 'l_joy_x', scale: 0.6} }
      tilt: { type: 'axis',       params: { name1: 'r_joy_y', scale: 0.6} }
      follow_r: {type: 'button',  params: { name1: 'circle' } }
      follow_l: {type: 'button',  params: { name1: 'square' } }
      center_head: {type: 'toggle',  params: { name1: 'triangle' } }
      projector_toggle: {type: 'toggle',  params: { name1: 'x' } }